.TH "validation" 3 "Fri Apr 15 2016" "Version 0.10.0-146_trunk" "libnetconf" \" -*- nroff -*-
.ad l
.nh
.SH NAME
validation \- Data Validation 
\fCRFC 6241\fP defines NETCONF :validate capability intended to allow validation of the configuration data\&. This capability specifies new operation <validate> and adds <test-option> parameter to the <edit-config> operation\&.
.PP
On the client side, libnetconf allows to create <validate> RPC as well as to specify <test-option> of <edit-config> RPC\&. When the :validate capability is supported by the server, the default <test-option> value is test-then-set, so each <edit-config> change is validated\&.
.PP
On the server side, libnetconf performs data validation on \fBdatastore parts\fP that provides validators\&. libnetconf use Relax NG schema to validate syntax of the datastore content and Schematron to check semantics\&. Validators are loaded as a standalone files generated by \fIlnctool(1)\fP, which is part of libnetconf standard instalation\&.
.PP
libnetconf automatically searches for the validators during \fBncds_new()\fP and \fBncds_new_transapi()\fP calls\&. Validators are supposed to be placed in the same directory as data model provided to the mentioned function as its model_path parameter\&. Alternatively, validators can be connected with the datastore manually, using \fBncds_set_validation()\fP\&. This function also allows to switch off validation on a specific datastore part\&.
.PP
.SS "lnctool(1) Usage"
.PP
Complete list of \fIlnctool(1)\fP's options can be displayed using -h option:
.PP
.PP
.nf
$ lnctool -h
.fi
.PP
.PP
\fIlnctool(1)\fP is used to perform the following 3 actions:
.PP
.IP "1." 4
\fIconvert\fP - converts YANG model to the YIN format
.IP "2." 4
\fIvalidation\fP - generates validation files for a given YANG data model
.IP "3." 4
\fItransapi\fP - prepares a transAPI module template
.PP
.PP
Each next action includes all the previous actions, so executing the \fItransapi\fP action generates also the YIN format of the data model and all the validation files\&. More information about using \fIlnctool(1)\fP for creating a transAPI modules can be found in the \fBTransaction API (transAPI)\fP section\&. Here we focus on the \fIvalidation\fP action\&.
.PP
As the main input, you have to specify the main YANG data model of the datastore (\fC--model\fP option)\&. If there are also some augmenting models, you should specify them as a parameter to the (multiple) \fC--augment-model\fP option(s)\&. If you need some imported data models, specify the path where to search for them as the \fC--search-path\fP option\&.
.PP
Based on a YANG data model, \fIlnctool(1)\fP generates all necessary files needed by libnetconf\&. Basically, it generates YIN format of the data model required by \fBncds_new()\fP and \fBncds_new_transapi()\fP functions\&. If you use some extension models via \fBncds_add_model()\fP or \fBncds_add_models_path()\fP, you have to specify also these models as \fIlnctool(1)\fP's <augment models> parameter\&.
.PP
The following commands generate validation files for the NACM data model:
.PP
.PP
.nf
$ cd libnetconf/models/
$ lnctool --model \&./ietf-netconf-acm\&.yang --output-dir \&./nacm/ validation
.fi
.PP
.PP
The output directory \fCnacm/\fP now contains generated NACM data model in YIN format, Relax NG schemas and Schematron XSL stylesheet for validation\&.
.PP
Path to the search directory should be also specified in the server source code to allow libnetconf to find imported data model (\fIietf-yang-types\&.yin\fP in this case)\&.
.PP
\fBNote:\fP
.RS 4
Return value checks are skipped in this example for simplicity\&. Do not copy-paste this example\&. Also note, that NACM is one of internal libnetconf datastores and it is not needed to add it manually by \fBncds_new()\fP\&. This is JUST a simple (stupid) example\&.
.RE
.PP
.PP
.PP
.nf
ds = ncds_new(NCDS_TYPE_FILE, "\&./models/nacm/ietf-netconf-acm\&.yin", NULL);
ncds_file_set_path(ds, ds_path);
ncds_init(ds);
ncds_add_models_path("\&./models/");
ncds_consolidate();
.fi
.PP
.PP
If the validators files are stored in the same directory as a basic data model (\fIietf-netconf-acm\&.yin\fP in this case), libnetconf automatically loads them during \fBncds_new()\fP or \fBncds_new_transapi()\fP calls\&. If you store the validators files somewhere else, \fBncds_set_validation()\fP function can be used to specify their location:
.PP
.PP
.nf
ncds_set_validation(ds, 1, "\&./models/nacm/ietf-netconf-acm-config\&.rng", "\&./models/nacm/ietf-netconf-acm-schematron\&.xsl");
.fi
.PP
.PP
If validators files are not found or validation is switched off (via \fBncds_set_validation()\fP with enable parameter set to 0), validation is not performed on such datastore part\&.
.PP
.SS "Data Model Features"
.PP
When the data model includes some \fCfeature\fP definition and corresponding \fCif-feature\fP statement(s), all such features are enabled for validation by default\&. If you want to enable only specific features (or disable all of them), you have to use the \fIlnctool(1)\fP's \fC--feature\fP option\&. The option can be use multiple times and the given value has the following form:
.PP
.PP
.nf
--feature module_name:feature_to_enable
.fi
.PP
.PP
If you want to disable all features of the module, use the following syntax:
.PP
.PP
.nf
--feature module_name:
.fi
.PP
.PP
Remember that if you have some augmenting modules, you should also set features of those augmenting modules\&. 
